{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Accessing geoprocessing tools\n", "\n", "In this page we will observe how you can search for geoprocessing tools and access them in your code."]}, {"cell_type": "markdown", "metadata": {"toc": true}, "source": ["<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n", "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Accessing-geoprocessing-tools\" data-toc-modified-id=\"Accessing-geoprocessing-tools-1\"><span class=\"toc-item-num\">1&nbsp;&nbsp;</span>Accessing geoprocessing tools</a></span><ul class=\"toc-item\"><li><span><a href=\"#Searching-for-geoprocessing-tools\" data-toc-modified-id=\"Searching-for-geoprocessing-tools-1.1\"><span class=\"toc-item-num\">1.1&nbsp;&nbsp;</span>Searching for geoprocessing tools</a></span></li><li><span><a href=\"#Pythonic-representation-of-tools-and-toolboxes\" data-toc-modified-id=\"Pythonic-representation-of-tools-and-toolboxes-1.2\"><span class=\"toc-item-num\">1.2&nbsp;&nbsp;</span>Pythonic representation of tools and toolboxes</a></span></li><li><span><a href=\"#Importing-toolboxes\" data-toc-modified-id=\"Importing-toolboxes-1.3\"><span class=\"toc-item-num\">1.3&nbsp;&nbsp;</span>Importing toolboxes</a></span><ul class=\"toc-item\"><li><span><a href=\"#Importing-toolbox-from-an-Item\" data-toc-modified-id=\"Importing-toolbox-from-an-Item-1.3.1\"><span class=\"toc-item-num\">1.3.1&nbsp;&nbsp;</span>Importing toolbox from an <code>Item</code></a></span></li><li><span><a href=\"#Importing-toolbox-from-a-geoprocessing-service-URL\" data-toc-modified-id=\"Importing-toolbox-from-a-geoprocessing-service-URL-1.3.2\"><span class=\"toc-item-num\">1.3.2&nbsp;&nbsp;</span>Importing toolbox from a geoprocessing service URL</a></span></li></ul></li><li><span><a href=\"#Tool-signature,-parameters-and-documentation\" data-toc-modified-id=\"Tool-signature,-parameters-and-documentation-1.4\"><span class=\"toc-item-num\">1.4&nbsp;&nbsp;</span>Tool signature, parameters and documentation</a></span></li></ul></li></ul></div>"]}, {"cell_type": "markdown", "metadata": {}, "source": ["<a id=\"searching-for-geoprocessing-tools\"></a>\n", "## Searching for geoprocessing tools\n", "\n", "Geoprocessing tools can be considered as web tools that can shared with others. Users organize their tools into toolboxes and share with on their GIS. You can search for geoprocessing tools just like you search for any other item.\n", "\n", "To search your GIS for geoprocessing toolboxes, specify `Geoprocessing Toolbox` as the item type."]}, {"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["import arcgis\n", "from arcgis.gis import GIS\n", "from IPython.display import display"]}, {"cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": ["gis = GIS('home')"]}, {"cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": ["toolboxes = gis.content.search('travel', 'Geoprocessing Toolbox', \n", "                               outside_org=True, max_items=3)"]}, {"cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [{"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://www.arcgis.com/home/item.html?id=6b34e48fc36e4096bfb933ab3d4b2ea7' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://www.arcgis.com/home/item.html?id=6b34e48fc36e4096bfb933ab3d4b2ea7' target='_blank'><b>DriveTimePolygonsService</b>\n", "                        </a>\n", "                        <br/>This tool calculates drive-time polygons in Lagos Metropolis. The drive-time polygons represent areas that can be reached within a given amount of time when departing from a facility and traveling along the road network. Optionally, the polygons can <img src='https://www.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/layers16.png' style=\"vertical-align:middle;\">Geoprocessing Toolbox by omolarakareem\n", "                        <br/>Last Modified: March 27, 2013\n", "                        <br/>0 comments, 316 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"DriveTimePolygonsService\" type:Geoprocessing Service owner:omolarakareem>"]}, "metadata": {}, "output_type": "display_data"}, {"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://www.arcgis.com/home/item.html?id=383c2039b89d43baa0010c3bf243b144' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://www.arcgis.com/home/item.html?id=383c2039b89d43baa0010c3bf243b144' target='_blank'><b>Ocean Currents</b>\n", "                        </a>\n", "                        <br/>Calculates the path of an unpowered vessel drifiting in ocean currents from a user defined point. Excludes wind or atmospheric conditions.<img src='https://www.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/layers16.png' style=\"vertical-align:middle;\">Geoprocessing Toolbox by esri_apac\n", "                        <br/>Last Modified: August 25, 2014\n", "                        <br/>1 comments, 165 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"Ocean Currents\" type:Geoprocessing Service owner:esri_apac>"]}, "metadata": {}, "output_type": "display_data"}, {"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://www.arcgis.com/home/item.html?id=097e4845a63f4bfe89445cb58ed99a17' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://www.arcgis.com/home/item.html?id=097e4845a63f4bfe89445cb58ed99a17' target='_blank'><b>World Origin Destination Cost Matrix</b>\n", "                        </a>\n", "                        <br/>OriginDestinationCostMatrix, currently in beta, is an ArcGIS Online service that helps you to create an origin-destination cost matrix from multiple origins to multiple destinations.  ArcGIS Online subscription required.<img src='https://www.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/layers16.png' style=\"vertical-align:middle;\">Geoprocessing Toolbox by esri\n", "                        <br/>Last Modified: June 21, 2016\n", "                        <br/>0 comments, 42 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"World Origin Destination Cost Matrix\" type:Geoprocessing Service owner:esri>"]}, "metadata": {}, "output_type": "display_data"}], "source": ["for toolbox in toolboxes:\n", "    display(toolbox)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["<a id=\"pythonic-representation-of-tools-and-toolboxes\"></a>\n", "## Pythonic representation of tools and toolboxes\n", "In ArcGIS API for Python, geoprocessing toolboxes are represented as Python modules and the individual tools as Python functions. These tools, represented as Python functions, take in a set of input parameters and return one or more output values.\n", "\n", "To use custom geoprocessing tools, users simply import that toolbox as a module in their programs and call functions within the module."]}, {"cell_type": "markdown", "metadata": {}, "source": ["<a id=\"importing-toolboxes\"></a>\n", "## Importing toolboxes\n", "\n", "The `import_toolbox()` function in the `arcgis.geoprocessing` module imports geoprocessing toolboxes as native Python modules. It accepts a toolbox location which could be a Geoprocessing Toolbox item in your GIS, or a URL to a Geoprocessing Service.\n", "\n", "Developers can then call the functions available in the imported module to invoke these tools. Let us see how to import toolboxes from these two sources.\n", "\n", "<a id=\"importing-toolbox-from-an-item\"></a>\n", "### Importing toolbox from an `Item`\n", "The code snippet below shows how the Ocean Currents toolbox above can be imported as a module:"]}, {"cell_type": "code", "execution_count": 6, "metadata": {"collapsed": true}, "outputs": [], "source": ["from arcgis.geoprocessing import import_toolbox"]}, {"cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [{"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://www.arcgis.com/home/item.html?id=383c2039b89d43baa0010c3bf243b144' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://www.arcgis.com/home/item.html?id=383c2039b89d43baa0010c3bf243b144' target='_blank'><b>Ocean Currents</b>\n", "                        </a>\n", "                        <br/>Calculates the path of an unpowered vessel drifiting in ocean currents from a user defined point. Excludes wind or atmospheric conditions.<img src='https://www.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/layers16.png' style=\"vertical-align:middle;\">Geoprocessing Toolbox by esri_apac\n", "                        <br/>Last Modified: August 25, 2014\n", "                        <br/>1 comments, 165 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"Ocean Currents\" type:Geoprocessing Service owner:esri_apac>"]}, "execution_count": 7, "metadata": {}, "output_type": "execute_result"}], "source": ["ocean_currents_toolbox = toolboxes[1]\n", "ocean_currents_toolbox"]}, {"cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": ["ocean_currents = import_toolbox(ocean_currents_toolbox)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The `import_toolbox()` function inspects the geoprocessing toolbox and dynamically generates a Python module containing a function for each tool within the toolbox. Invoking the function invokes the corresponding geoprocessing tool. \n", "\n", "The code snippet below uses Python's `inspect` module to list the public functions in the imported module. Developers will typically use their IDE's intellisense to discover the functions in the module."]}, {"cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [{"data": {"text/plain": ["['message_in_a_bottle']"]}, "execution_count": 9, "metadata": {}, "output_type": "execute_result"}], "source": ["import inspect\n", "\n", "# list the public functions in the imported module\n", "[ f[0] for f in inspect.getmembers(ocean_currents, inspect.isfunction) \n", "             if not f[0].startswith('_')]"]}, {"cell_type": "markdown", "metadata": {}, "source": ["<a id=\"importing-toolbox-from-a-geoprocessing-service-url\"></a>\n", "### Importing toolbox from a geoprocessing service URL\n", "\n", "The example below uses a URL to a geoprocessing service to import a geoprocessing toolbox:"]}, {"cell_type": "code", "execution_count": 10, "metadata": {"collapsed": true}, "outputs": [], "source": ["zion_toolbox_url = 'http://gis.ices.dk/gis/rest/services/Tools/ExtractZionData/GPServer'\n", "zion = import_toolbox(zion_toolbox_url)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["<a id=\"tool-signature-parameters-and-documentation\"></a>\n", "## Tool signature, parameters and documentation\n", "\n", "The function for invoking the geoprocessing tool includes documentation about that tool. This doc shows up using your IDE's intellisense and can also be accessed using Python's help function:"]}, {"cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Help on function extract_zion_data:\n", "\n", "extract_zion_data(layers_to_clip:str=\"['Research_areas', 'Roads', 'Springs', 'Zion park boundary']\", area_of_interest:arcgis.features.feature.FeatureSet={'exceededTransferLimit': False, 'fields': [{'name': 'FID', 'alias': 'FID', 'type': 'esriFieldTypeOID'}, {'name': 'Id', 'alias': 'Id', 'type': 'esriFieldTypeInteger'}, {'name': 'Shape_Length', 'alias': 'Shape_Length', 'type': 'esriFieldTypeDouble'}, {'name': 'Shape_Area', 'alias': 'Shape_Area', 'type': 'esriFieldTypeDouble'}], 'features': [], 'displayFieldName': '', 'spatialReference': {'wkid': None}, 'geometryType': 'esriGeometryPolygon'}, feature_format:str='File Geodatabase - GDB - .gdb', raster_format:str='ESRI GRID - GRID', gis=None) -> arcgis.geoprocessing._types.DataFile\n", "            \n", "     Extracts the specified Layers in the specified Area of Interest to the selected Formats and returns all the data in a zip file. This tool is intended primarily for use as a part of a geoprocessing service. Full step by step instructions for making a Clip and Ship / Data Extraction geoprocessing service can be found here (under construction).When using this tool as a part of a geoprocessing service, first copy the tool into a custom toolbox. After copying, edit the model and configure it if necessary.\n", "    \n", "    Parameters:\n", "    \n", "       layers_to_clip: Layers to Clip (str). Required parameter.  The Layers to be clipped. Layers should be either raster layers or feature layers.\n", "          Choice list:['Research_areas', 'Tracts', 'Roads', 'Trails', 'Springs', 'Streams', 'Zion park boundary', 'Hillshade']\n", "    \n", "       area_of_interest: Area of Interest (FeatureSet). Required parameter.  The area by which the layers will be clipped.\n", "    \n", "       feature_format: Feature Format (str). Required parameter.  The format in which the output features will be delivered.\n", "          Choice list:['File Geodatabase - GDB - .gdb', 'Shapefile - SHP - .shp', 'Geographic Markup Language - GML - .gml', 'OpenGIS KML Encoding Standard - OGCKML - .kmz', 'Autodesk AutoCAD - DXF_R2007 - .dxf', 'Autodesk AutoCAD - DWG_R2007 - .dwg', 'Bentley Microstation Design (V8) - DGN_V8 - .dgn', 'Adobe 3D PDF - PDF - .pdf', 'Autodesk AutoCad DWF - DWF - .dwf', 'Scalable Vector and Graphics (SVG) - SVG - .svg', 'Scalable Vector and Graphics (SVG) - SVG - .svgz']\n", "    \n", "       raster_format: Raster Format (str). Required parameter.  The format in which the output rasters will be delivered.\n", "          Choice list:['ESRI GRID - GRID', 'File Geodatabase - GDB - .gdb', 'ERDAS IMAGINE - IMG - .img', 'Tagged Image File Format - TIFF - .tif', 'Graphic Interchange Format - GIF - .gif', 'Joint Photographics Experts Group - JPEG - .jpg', 'Joint Photographics Experts Group - JPEG 2000 - .jp2', 'Bitmap - BMP - .bmp', 'Portable Network Graphics - PNG - .png']\n", "    \n", "            gis: Optional, the GIS on which this tool runs. If not specified, the active GIS is used.\n", "    \n", "    \n", "    Returns: \n", "       output_zip_file - Output Zip File as a DataFile\n", "    \n", "    See http://gis.ices.dk/gis/rest/directories/arcgisoutput/Tools/ExtractZionData_GPServer/Tools_ExtractZionData/ExtractZionData.htm for additional help.\n", "\n"]}], "source": ["help(zion.extract_zion_data)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["As shown in the example above, tool functions are annotated using [type hints](https://www.python.org/dev/peps/pep-0484/) to help indicate the input they accept and the output they produce. The function signature includes default values for the input parameters, so the caller doesn't have to specify them unless required. Parameter documentation includes a description of each parameter, it's expected type, and whether it is required or optional. If the parameter accepts from a list of input values, that list is included with the documentation as a 'Choice List'. The documentation includes the type and description of the functions return value."]}, {"cell_type": "markdown", "metadata": {}, "source": ["Next, head over to the topic [Using geoprocessing tools](https://developers.arcgis.com/python/guide/using-geoprocessing-tools/) to see how these tools can be used in Python scripts."]}], "metadata": {"anaconda-cloud": {}, "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.2"}, "toc": {"base_numbering": 1, "nav_menu": {}, "number_sections": true, "sideBar": true, "skip_h1_title": false, "title_cell": "Table of Contents", "title_sidebar": "Contents", "toc_cell": true, "toc_position": {}, "toc_section_display": true, "toc_window_display": true}}, "nbformat": 4, "nbformat_minor": 1}